---
displayed_sidebar: "Chinese"
---

# to_binary

## 功能

根据指定的二进制格式 (`binary_type`)，将 VARCHAR 字符串转换为二进制类型。支持的二进制格式包括 Hex, Base64，和 UTF-8。如果未指定，默认为 Hex。

该函数从 3.0 版本开始支持。

## 语法

```Haskell
to_binary(str[, binary_type])
```

## 参数说明

- `str`: 必选，待转换的字符串，VARCHAR 类型。
- `binary_type`：可选，指定的二进制格式，VARCHAR 类型。有效值：`hex`，`encode64`，`utf8`。

  - `hex` (默认值): 该函数会将输入字符串作为十六进制字符串处理（'0123456789abcdef'），比如 `"abab"` 会转换为 `x'abab'`。如果输入值非法，返回空 binary 而非抛异常。`hex` 格式下该函数对大小写不敏感。
  - `encode64`: 该函数会将输入字符串作为 Base64 字符串处理，比如 `"YWJhYg=="` 会解码为 `x'abab'`。如果输入值非法，返回空 binary 而非抛异常。
  - `utf8`: 该函数直接将输入字符串转换为二进制类型，不做任何转换处理。

## 返回值说明

返回 VARBINARY 类型的二进制数值。

## 示例

以下示例在启动 MySQL 客户端时添加了 `--binary-as-hex` 选项，会默认以 `hex` 格式展示 BINARY 数据。

```Plain
mysql> select to_binary('abab', 'hex');
+----------------------------------------------------+
| to_binary('ABAB', 'hex')                           |
+----------------------------------------------------+
| 0xABAB                                             |
+----------------------------------------------------+
1 row in set (0.01 sec)

mysql> select to_binary('U1RBUlJPQ0tT', 'encode64');
+------------------------------------------------------------------------------+
| to_binary('U1RBUlJPQ0tT', 'encode64')                                        |
+------------------------------------------------------------------------------+
| 0x53544152524F434B53                                                         |
+------------------------------------------------------------------------------+
1 row in set (0.00 sec)

mysql> select to_binary('STARROCKS', 'utf8');
+----------------------------------------------------------------+
| to_binary('STARROCKS', 'utf8')                                 |
+----------------------------------------------------------------+
| 0x53544152524F434B53                                           |
+----------------------------------------------------------------+
1 row in set (0.00 sec)

-- 输入值不合法，返回空 binary。
mysql> select to_binary('U1RBUlJPQ0tT', 'hex');
+--------------------------------------------------------------------+
| to_binary('U1RBUlJPQ0tT', 'hex')                                   |
+--------------------------------------------------------------------+
| 0x                                                                 |
+--------------------------------------------------------------------+
1 row in set (0.00 sec)

```

## 相关文档

- [from_binary](from_binary.md)
- [BINARY/VARBINARY](../../sql-statements/data-types/BINARY.md)
